A UMD cross-domain Ajax implementation.
npm i xdr
Use this library if you need to support IE8 (cross-domain) and want robust error handling by convention. Requires server-side code to respond following the convention for overriding the response status code and error messages see the server implementation notes.
The server must at a minimum send the appropriate headers for CORS support, see server.js for example headers.
In addition, in order to support the XDomainRequest object for IE 8/9 the server must process requests that do not contain a Content-Type header and the client must know the type of data the server responds with.
To support error handling for instances when the http status code is not available the server should reply with a packet that contains code and error properties.
A successful 2xx response may be returned as:
{code: 202, message: "Request accepted"}
Whereas for an error the server could reply with:
{code: 400, error: {message: "Bad request"}}
The fields used for extracting status codes and error messages are configurable using the status and error options.
Full support is deemed to be browsers that can make cross domain requests and access the response headers:
Access-Control-Expose-Headers response header so assertions fail on the response headers.getAllResponseHeaders().GET and POST methods are allowed.XDomainRequest object.async option is ignored for XDomainRequest instances.XDomainRequest.XDomainRequest cannot set request headers, specifically no Content-Type header may be set.XDomainRequest.See XDomainRequest Limitations for more information.
ajax(options [, callback])
The ajax method accepts an options object that controls the request behaviour and returns an object containing the underlying transport used for the request.
ajax({url: "/api", type: 'json'}, function(response) {
// ...
});
url The URL to connect to.method The HTTP method.headers An object containing HTTP request headers.timeout A timeout for the request in milliseconds.data Data to send with the request.type The expected data type, one of json, jsonp or text.params Query string parameters to append to the URL.callback A callback for responses, if the callback parameter is specified it overwrites this field.async Whether the request is asynchronous, default is true.parameter Send the data as the named query string parameter.error The name of a property of the response object that contains error information, default is error.status The name of a property of the response object that contains a status code, default is code.jsonp The name of the callback query string variable for jsonp requests, default is callback.delay A delay before invoking send() in milliseconds (XDomainRequest only).mime A MIME type passed to overrideMimeType(), (XMLHttpRequest only).credentials Authentication credentials (XMLHttpRequest only).fields Properties to apply to the request instance (XMLHttpRequest only).Invoking ajax() returns false when the current browser does not support
JSON, XMLHttpRequest or XDomainRequest, otherwise an object is returned
with the following properties:
xhr The underlying transport for the request, will be one of XMLHttpRequest, XDomainRequest or a Jsonp instance.abort A function thay aborts the request.cors A boolean indicating whether the browser supports CORS.ie Object that determines whether the current browser is Internet Explorer and which version of Internet Explorer is in use.url The final URL including query string parameters.jsonp A boolean indicating whether the request was made using jsonp.Note that the return value will also be false if the options object is invalid, ie, no options were supplied or an unsupported type was specified.
The callback is invoked with a response object that contains the following properties:
status The HTTP response status code.data The response data, if the type is jsonp or json this will be the.
decoded javascript object.xhr A reference to the transport instance used for the request.headers An object containing response headers, will be null when.
response headers are not available.error An Error instance or null if no error occurred.ajax.defaults = {
method: 'GET',
timeout: 10000,
delay: 0,
async: true,
parameter: 'packet',
jsonp: 'callback',
error: 'error',
status: 'code',
headers: {
'X-Requested-With': 'XMLHttpRequest'
}
}
A reference to the transport used for jsonp requests.
Exposes the object containing type converters. This object may be used to create additional supported types.
ajax.converters = {
text: {
mime: 'text/plain',
encode: function(data){return data;},
decode: function(data){return data;}
},
json: {
mime: 'application/json',
encode: function(data) {
return JSON.stringify(data);
},
decode: function(data) {
return JSON.parse(data);
}
}
}
Information about Internet Explorer, for example:
ajax.ie = {
browser: true,
version: 9
}
var opts = {
url: '/api',
type: 'json'
};
ajax(opts, function(response) {
console.log(response);
});
var data = {id: 10};
var opts = {
url: '/api',
method: 'POST',
type: 'json',
data: data
};
ajax(opts, function(response) {
console.log(response);
});
Requests using the jsonp transport ignore the method option as GET is the only method available.
var opts = {
url: '/api',
type: 'jsonp'
};
ajax(opts, function(response) {
console.log(response);
});
Or to send a JSON and URL-encoded request packet for a JSONP request also specify some data:
var data = {id: 10};
var opts = {
url: '/api',
type: 'jsonp',
data: data
};
ajax(opts, function(response) {
console.log(response);
});
The request packet will be sent as the packet query string variable, configurable using the parameter option.
To handle errors you only need to test the error property of the response object, for example:
function error(status, err) {
console.log(status + ": " + err.message);
}
var opts = {url: '/api', type: 'json'};
ajax(opts, function(response) {
if(response.error) {
return error(response.status, response.error);
}
// ...
});
The error property of the response object is always an Error instance.
You may abort a request by calling the abort function of the return object. In the case of the jsonp type, this function is a non-operation.
var opts = {url: '/api', type: 'json'};
var req = ajax(opts, function(response) {
// ...
});
req.abort();
Developer workflow is via [gulp][] but should be executed as npm scripts to enable shell execution where necessary.
Run the headless test suite using [phantomjs][]:
npm test
To run the tests in a browser context open test/index.html or use the server npm start.
Serve the test files from a web server with:
npm start
Run the test suite and generate code coverage:
npm run cover
Run the source tree through [eslint][]:
npm run lint
Remove generated files:
npm run clean
Compile the test specifications:
npm run spec
Generate instrumented code from lib in instrument:
npm run instrument
Generate the project readme file (requires mdp):
npm run readme
When a browser does not support exposing response headers only the following simple headers are accessible:
Generated by mdp(1).
FAQs
Cross-browser and cross-domain ajax implementation
The npm package xdr receives a total of 1 weekly downloads. As such, xdr popularity was classified as not popular.
We found that xdr demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
require(esm) backported to Node.js 20, easing the transition to ESM-only packages and reducing complexity for developers as Node 18 nears end-of-life.
Security News
PyPI now supports iOS and Android wheels, making it easier for Python developers to distribute mobile packages.
Security News
Create React App is officially deprecated due to React 19 issues and lack of maintenance—developers should switch to Vite or other modern alternatives.